Today, we are issuing the 4.16.1 patch release.

Fixes in Prisma Client

• Field references are not available on extended clients
• 4.16.x cannot wrap $extend in factory function when compilerOptions.composite is true
• Prisma Schema Type inside a Type not generating a right Payload
• Query in findMany in prisma extends returns a wrong type
• 4.16.0 Count query is not returning the right type when in a transaction
• FindMany returns wrong type after extending prisma client
• Can't specify $queryRawUnsafe return type after extending prisma client

🌟 Help us spread the word about Prisma by starring the repo or tweeting about the release. 🌟

Highlights

This release promotes the following Preview features to General Availability:

• Prisma Client extensions
• Ordering by nulls first and last
• Count by filtered relation

Prisma Client extensions are Generally Available

Today, we’re very excited to announce that Prisma Client extensions are Generally Available and production-ready! This means you can use the feature without the clientExtensions Preview feature flag.🚀

Prisma Client extensions are a powerful new feature for adding functionality on top of your Prisma Client in a type-safe manner. With this feature, you can create simple, but flexible solutions.

Prisma Client extensions have 4 different types of components that can be included in an extension:

• Result extensions components: add custom fields and methods to query result objects, for example, virtual/computed fields.
• Model extensions components: enable you to add new methods to your models alongside existing model methods such as findMany.
• Query extensions components: let you hook into the lifecycle of a query and perform side effects, modify query arguments, or modify the results in a type-safe way. These are an alternative to middleware that provide complete type safety and can be applied in an ad-hoc manner to different extensions.
• Client extensions components: allow you to add new top-level methods to Prisma Client. You can use this to extend Prisma Client with functionality that isn’t tied to specific models.

const prisma = new PrismaClient().$extends({
  name: "extension-name",
  result: { /* ... */ },
  model: { /* ... */ },
  query: { /* ... */ },
  client: { /* ... */ },
});

You can also create and publish extensions for others to use. Learn more about how to share extensions in our documentation.

More features and changes made to Client Extensions

We also made the following improvements to Prisma Client extensions in preparation for General Availability:

• Added a top-level $allOperations method for query component that captures all model operations as well as top-level raw queries. Refer to our documentation for more information.

  const prisma = new PrismaClient().$extends({
    query: {
      $allOperations({ args, query, operation, model }) {
        /* your extension's logic here */
      }
    }
  })

• Prisma.validator can now also be used for extended types:

  const prisma = new PrismaClient().$extends({/* ... */})
  const data = Prisma.validator(prisma, 'user', 'findFirst', 'select')({
    id: true,
  })

• query callbacks for $queryRaw and $executeRaw will always receive Sql instance as args. This instance can be used to compose a new query using Prisma.sql:

  const prisma = new PrismaClient().$extends({
    query: {
      $queryRaw({ args, query }) {
        return query(Prisma.sql`START TRANSACTION; ${args}; COMMIT;`)
      }
    }
  })

• $on cannot be called after extending Prisma Client. Therefore, if you want to use event handlers together with extensions, we recommend using the $on method before $extends.

  const prisma = new PrismaClient()
    .$on(/* ... */)
    .$extends({/* ... */})

• We updated the import path for utilities used for authoring extension to @ prisma/client/extension rather than @ prisma/client

  + import { Prisma } from "@ prisma/client/extension"
  - import { Prisma } from "@ prisma/client"

Deprecating Middleware

We also took this opportunity to deprecate Prisma Client’s middleware. We recommend using to using Prisma Client query extension components which can be used to achieve the same functionality and with better type safety.

🚧 Middleware will still be available in Prisma Client’s API. However, we recommend using Prisma Client extensions over middleware.

Ordering by nulls first and last is now Generally Available

Starting with this release, we’re excited to announce that orderByNulls is now Generally Available! This means you can use the feature without the orderByNulls Preview feature flag.🌟

We introduced this feature in 4.1.0 to enable you to sort records with null fields to either appear at the beginning or end of the result.

The following example query sorts posts by updatedAt, with records having a null value at the end of the list:

await prisma.post.findMany({
  orderBy: {
    updatedAt: { sort: 'asc', nulls: 'last' },
  },
})

To learn more about this feature, refer to our documentation.

We’re excited to see what you will build! Feel free to share with us what you build on Twitter, Slack, or Discord.

Count by filtered relation is now Generally Available

This release moves the filteredRelationCount Preview feature to General Availability! This means you can use the feature without the filteredRelationCount Preview feature flag.

We first introduced this feature in 4.3.0 to add the ability to count by filtered relations.

The following query, for example, counts all posts with the title “Hello!”:

await prisma.user.findMany({
  select: {
    _count: {
      select: {
        posts: { where: { title: 'Hello!' } },
      },
    },
  },
})

To learn more about this feature, refer to our documentation.

Introspection warnings for expression indexes

In the last two releases, 4.13.0 and 4.14.0, we added 9 introspection warnings. These warnings surface features in use in your database that cannot currently be represented in the Prisma schema.

In this release, we’re adding one more introspection warning to the list: expression indexes.

On database introspection, the Prisma CLI will surface the feature with a warning, and a comment in your Prisma schema for sections for each feature in use. The warnings will also contain instructions for workarounds on how to use the feature.

Fixes and improvements

Prisma Client

• Attach comments to enum values
• Extend Prisma Client
• Triple-slash Comments should attach to Composite Types
• Nested disconnect fails on MongoDB with extendedWhereUnique
• [ClientExtensions, TypeScript] Fields of custom type aren't available when using the ClientExtensions preview-feature, unless select'd explicitly.
• Extensions incorrect typings generated (casing)
• Misleading error message of prisma generate when running it directly after installing prisma
• Prisma.validator: with clientExtensions enabled, Typescript can no longer compute types
• enum docstrings do not make it to the prisma client
• VScode behavior is very slow while using clientExtensions
• Client extensions in interactive transactions are bound to the base client
• $runCommandRaw is not passing the expected data to middleware or client extension
• PCE: Improve runtime types in raw query extensions
• Sequential transactions run out of order when using client extensions and middleware
• Client Extension: Make .prismaVersion.client available on "@prisma/client/scripts/default-index"
• Cannot create record with Prisma.DbNull when clientExtensions enabled
• Extended client raw queries fail when using the Prisma.sql helper
• jsonProtocol: array shortcut is missing for distinct field
• Prisma Client Extension: support Prisma.validator
• Prisma Client: make clientExtensions GA
• PCE: Query extensions of $queryRawUnsafe also triggers $allModels.$allOperations
• PCE: $on applied to an extended client is also bound to the parent client
• Type "never" returned from nested properties when using "select" after enabling data proxy + accelerate
• $queryRaw* is broken in interactive transactions together with clientExtensions in 4.16.0-dev.17
• Deploying to an offline environment fails because it tries to download a Prisma engine checksum file
• jsonProtocol: Wrong error message shown for validation error for checked/unchecked types
• Bug: FindXOrThrow don't get batched on the engine

Prisma Migrate

• Allow skipping sha checksum
• Documentation not available in DMMF for MongoDB types
• prisma db pull gets rid of @ default(uuid()) on re-introspection

Language tools (e.g. VS Code)

• Go to Definition does not work when target model contains a field with a type name that starts with the same name

Prisma Studio

• Error: spawn xdg-open ENOENT on prisma studio

📺 Join us for another "What's new in Prisma" live stream

Learn about the latest release and other news from the Prisma community by joining us for another "What's new in Prisma" live stream.

The stream takes place on YouTube on Thursday, June 22 at 5 pm Berlin | 8 am San Francisco.